Lấy báo giá FX

Lấy báo giá cho một nhu cầu chuyển đổi ngoại hối cụ thể. API hoạt động theo hai chế độ:

• FIRM — Merchant truyền amount cụ thể → Baokim trả quote_id có thời hạn hiệu lực (expires_at), tỷ giá đã cam kết cho số tiền đó. Dùng để thực thi tại Thực thi chuyển đổi.
• INDICATIVE — Merchant không truyền amount → Baokim trả tỷ giá tham khảo để hiển thị, không có quote_id thực thi. Khi muốn chuyển đổi phải gọi lại loại FIRM

Luồng xử lý

Đường dẫn

• URL: /api/v1/fx/quote
• Method: POST

Request

Tham số	Loại dữ liệu	Bắt buộc	Mô tả
request_id	string(50)	Có	Xem mục 3 Giới thiệu
request_time	string(19)	Có	Xem mục 3 Giới thiệu
merchant_code	string(20)	Có	Xem mục 3 Giới thiệu
trade_type	string(4)	Có	Loại hình giao dịch từ góc nhìn Merchant: SELL (Merchant bán ngoại tệ, thu VND) hay BUY (Merchant dùng VND mua ngoại tệ)
from_currency	string(3)	Có	Đồng tiền Merchant đang có (đồng tiền nguồn), ví dụ USD
to_currency	string(3)	Có	Đồng tiền Merchant muốn nhận (đồng tiền đích), ví dụ VND
amount	decimal(18,2)	Không	Số tiền dự kiến chuyển đổi, lớn hơn 0. Có truyền → báo giá FIRM (có quote_id, thực thi được). Không truyền → báo giá INDICATIVE (chỉ tham khảo, không quote_id).
fixed_side	string(4)	Không	Phía cố định của amount, chỉ có ý nghĩa khi truyền amount. FROM (mặc định): amount là số tiền nguồn Merchant muốn bán hết, hệ thống tính số tiền nhận. TO: amount là số tiền đích Merchant cần nhận đúng, hệ thống tính số tiền nguồn cần có.

Quy tắc validation

• Đúng một trong hai from_currency/to_currency phải là VND; vi phạm → mã 422
• trade_type phải khớp chiều: SELL ⇔ from_currency ngoại tệ, to_currency VND; BUY ⇔ from_currency VND, to_currency ngoại tệ. Không khớp → mã 422
• Ngoại tệ hỗ trợ: đồng ngoại tệ phải nằm trong danh mục cấu hình cho Merchant; ngoài danh mục → mã 404
• amount: nếu truyền phải > 0; khi fixed_side chỉ về phía VND, amount phải số nguyên; vi phạm → mã 422
• fixed_side mà không amount: hệ thống bỏ qua fixed_side, trả báo giá INDICATIVE

Ví dụ Request — FIRM (Merchant có 10.000 USD, muốn bán lấy VND)

{
  "request_id": "MERCHANT1234BK202606050001",
  "request_time": "2026-06-05 10:15:30",
  "merchant_code": "MERCHANT1234",
  "trade_type": "SELL",
  "from_currency": "USD",
  "to_currency": "VND",
  "amount": 10000.00,
  "fixed_side": "FROM"
}

Ví dụ Request — INDICATIVE (chỉ lấy tỷ giá tham khảo)

{
  "request_id": "MERCHANT1234BK202606050005",
  "request_time": "2026-06-05 10:15:30",
  "merchant_code": "MERCHANT1234",
  "trade_type": "BUY",
  "from_currency": "VND",
  "to_currency": "USD"
}

Response

Tham số	Loại dữ liệu	Bắt buộc	Mô tả
response_code	int(4)	Có	Mã kết quả
response_message	string(200)	Có	Mô tả mã kết quả
merchant_code	string(20)	Có	Mã merchant
data	Object	Có	Chi tiết báo giá (xem bảng dưới)

Cấu trúc data

Tham số	Loại dữ liệu	Mô tả
quote_type	string(10)	Loại báo giá: FIRM hoặc INDICATIVE
quote_id	string(50)	Mã báo giá dùng để thực thi tại Thực thi chuyển đổi. Null khi quote_type = INDICATIVE.
trade_type	string(4)	Loại hình giao dịch, trả lại theo request
currency_pair	string(10)	Cặp tiền tệ chuẩn hóa, luôn ở dạng NGOẠI_TỆ/VND (ví dụ USD/VND), bất kể chiều giao dịch
rate	decimal(18,4)	Tỷ giá áp dụng, biểu diễn theo currency_pair: 1 đơn vị ngoại tệ = rate VND. Với FIRM: tỷ giá đã áp theo bậc số tiền yêu cầu. Với INDICATIVE: tỷ giá tham khảo.
from_currency	string(3)	Đồng tiền nguồn
from_amount	decimal(18,2)	Số tiền nguồn. Nếu fixed_side = TO, đây là giá trị do hệ thống tính. Null khi quote_type = INDICATIVE.
to_currency	string(3)	Đồng tiền đích
to_amount	decimal(18,2)	Số tiền đích Merchant sẽ nhận. Nếu fixed_side = FROM, đây là giá trị do hệ thống tính. Null khi quote_type = INDICATIVE.
fee_amount	decimal(18,2)	Phí chuyển đổi (hiện tại: 0, phí đã bao gồm trong tỷ giá)
fee_currency	string(3)	Đồng tiền của phí
quoted_at	string(19)	Thời điểm sinh báo giá (GMT+7), định dạng YYYY-MM-DD HH:MM:SS
expires_at	string(19)	Thời hạn hiệu lực của báo giá. Sau thời điểm này, quote_id không thực thi được. TTL mặc định: x phút. Null khi quote_type = INDICATIVE.

Ví dụ Response — FIRM

{
  "response_code": 200,
  "response_message": "Success",
  "merchant_code": "MERCHANT1234",
  "data": {
    "quote_type": "FIRM",
    "quote_id": "FXQ0605A7K2M9XD41",
    "trade_type": "SELL",
    "currency_pair": "USD/VND",
    "rate": 26450.0000,
    "from_currency": "USD",
    "from_amount": 10000.00,
    "to_currency": "VND",
    "to_amount": 264500000,
    "fee_amount": 0,
    "fee_currency": "VND",
    "quoted_at": "2026-06-05 10:15:30",
    "expires_at": "2026-06-05 10:25:30"
  }
}

Ví dụ Response — INDICATIVE

{
  "response_code": 200,
  "response_message": "Success",
  "merchant_code": "MERCHANT1234",
  "data": {
    "quote_type": "INDICATIVE",
    "quote_id": null,
    "trade_type": "BUY",
    "currency_pair": "USD/VND",
    "rate": 26430.0000,
    "from_currency": "VND",
    "from_amount": null,
    "to_currency": "USD",
    "to_amount": null,
    "fee_amount": 0,
    "fee_currency": "VND",
    "quoted_at": "2026-06-05 10:15:30",
    "expires_at": null
  }
}

Mã lỗi

Mã Response	Thông báo Response	Mô tả
200	Success
101	System Error	Lỗi không mong muốn phía Baokim
110	Merchant code invalid	merchant_code không xác định hoặc không được phép
120	Invalid signature	Header Signature không hợp lệ
404	Currency not supported	Ngoại tệ yêu cầu không nằm trong danh mục Merchant
422	Validation Error	Trường request sai chiều giao dịch, không có VND, amount không hợp lệ…
423	FX rate temporarily unavailable	Không có tỷ giá tin cậy khả dụng
429	Too many requests	Vượt quá giới hạn tỷ lệ cho Merchant